sgdk
sound.h File Reference

Audio / Sound stuff. More...

Go to the source code of this file.

Defines

#define SOUND_PCM_CH_AUTO   0x00
#define SOUND_PCM_CH1   Z80_DRV_CH0_SFT
#define SOUND_PCM_CH2   Z80_DRV_CH1_SFT
#define SOUND_PCM_CH3   Z80_DRV_CH2_SFT
#define SOUND_PCM_CH4   Z80_DRV_CH3_SFT
#define SOUND_PCM_CH1_MSK   Z80_DRV_CH0
#define SOUND_PCM_CH2_MSK   Z80_DRV_CH1
#define SOUND_PCM_CH3_MSK   Z80_DRV_CH2
#define SOUND_PCM_CH4_MSK   Z80_DRV_CH3
#define SOUND_RATE_32000   0
#define SOUND_RATE_22050   1
#define SOUND_RATE_16000   2
#define SOUND_RATE_13400   3
#define SOUND_RATE_11025   4
#define SOUND_RATE_8000   5
#define SOUND_PAN_LEFT   0x80
#define SOUND_PAN_RIGHT   0x40
#define SOUND_PAN_CENTER   0xC0

Functions

u8 SND_isPlaying_PCM ()
 Return play status (Single channel PCM player driver).
void SND_startPlay_PCM (const u8 *sample, const u32 len, const u8 rate, const u8 pan, const u8 loop)
 Start playing a sample (Single channel PCM player driver).
If a sample was currently playing then it's stopped and the new sample is played instead.
void SND_stopPlay_PCM ()
 Stop playing (Single channel PCM player driver).
No effect if no sample was currently playing.
u8 SND_isPlaying_2ADPCM (const u16 channel_mask)
 Return play status of specified channel (2 channels ADPCM player driver).
void SND_startPlay_2ADPCM (const u8 *sample, const u32 len, const u16 channel, const u8 loop)
 Start playing a sample on specified channel (2 channels ADPCM player driver).
If a sample was currently playing on this channel then it's stopped and the new sample is played instead.
void SND_stopPlay_2ADPCM (const u16 channel)
 Stop playing the specified channel (2 channels ADPCM player driver).
No effect if no sample was currently playing on this channel.
u8 SND_isPlaying_4PCM_ENV (const u16 channel_mask)
 Return play status of specified channel (4 channels PCM ENV player driver).
void SND_startPlay_4PCM_ENV (const u8 *sample, const u32 len, const u16 channel, const u8 loop)
 Start playing a sample on specified channel (4 channels PCM ENV player driver).
If a sample was currently playing on this channel then it's stopped and the new sample is played instead.
void SND_stopPlay_4PCM_ENV (const u16 channel)
 Stop playing the specified channel (4 channels PCM ENV player driver).
No effect if no sample was currently playing on this channel.
void SND_setVolume_4PCM_ENV (const u16 channel, const u8 volume)
 Change envelop / volume of specified channel (4 channels PCM ENV player driver).
u8 SND_getVolume_4PCM_ENV (const u16 channel)
 Return envelop / volume level of specified channel (4 channels PCM ENV player driver).
u8 SND_isPlaying_MVS ()
 Return play status for FM (MVS music player driver).
void SND_startPlay_MVS (const u8 *music, const u8 loop)
 Start playing the specified FM track (MVS music player driver).
void SND_stopPlay_MVS ()
 Stop playing FM music (MVS music player driver).
void SND_setTempo_MVS (u8 tempo)
 Set the FM music tempo (MVS music player driver).
void SND_startDAC_MVS (const u8 *sample, u16 size)
 Start playing the specified DAC sample (MVS music player driver).
void SND_stopDAC_MVS ()
 Stop playing DAC sample (MVS music player driver).
u8 SND_isPlayingPSG_MVS ()
 Return play status for PSG (MVS music player driver).
void SND_startPSG_MVS (const u8 *music)
 Start playing the specified PSG music (MVS music player driver).
void SND_stopPSG_MVS ()
 Stop playing PSG music.
void SND_enablePSG_MVS (u8 chan)
 Enable the specified PSG channel.
void SND_disablePSG_MVS (u8 chan)
 Disable the specified PSG channel.
void SND_startPlay_TFM (const u8 *song)
 Start playing the specified TFM track (TFM music player driver).
void SND_stopPlay_TFM ()
 Stop playing music (TFM music player driver).
u8 SND_isPlaying_VGM ()
 Return play state of VGM driver.
void SND_startPlay_VGM (const u8 *song)
 Start playing the specified VGM track (VGM music player driver).
void SND_stopPlay_VGM ()
 Stop playing music (VGM music player driver).
void SND_resumePlay_VGM ()
 Resume playing music after stopping with SND_stopPlay_VGM.
void SND_playSfx_VGM (const u8 *sfx, u16 len)
 Play a PCM sound effect while a VGM track is playing.
u8 SND_isPlaying_XGM ()
 Returns play music state (XGM music player driver).
void SND_startPlay_XGM (const u8 *song)
 Start playing the specified XGM track (XGM music player driver).
void SND_stopPlay_XGM ()
 Stop playing music (XGM music player driver).
void SND_resumePlay_XGM ()
 Resume playing music after stopping with SND_stopPlay_XGM (XGM music player driver).
u8 SND_isPlayingPCM_XGM (const u16 channel_mask)
 Return play status of specified PCM channel (XGM music player driver).
void SND_setPCM_XGM (const u8 id, const u8 *sample, const u32 len)
 Declare a new PCM sample (maximum = 255) for the XGM music player driver.
Sample id < 64 are reserved for music while others are used for SFX so if you want to declare a new SFX PCM sample use an id >= 64.
void SND_setPCMFast_XGM (const u8 id, const u8 *sample, const u32 len)
 Same as SND_setPCM_XGM but fast version.
This method assume that XGM driver is loaded and that 68000 has access to Z80 bus.
void SND_startPlayPCM_XGM (const u8 id, const u8 priority, const u16 channel)
 Play a PCM sample on specified channel (XGM music player driver).
If a sample was currently playing on this channel then priority of the newer sample should be are compared tthen it's stopped and the new sample is played instead.
void SND_stopPlayPCM_XGM (const u16 channel)
 Stop play PCM on specified channel (XGM music player driver).
No effect if no sample was currently playing on this channel.
u16 SND_getCPULoad_XGM ()
 Returns an estimation of the Z80 CPU load (XGM driver).
It returns value between ~80% (minimum value) to >100% (if we have some frames late).
WARNING: You should call this method at each frame to get meaningful value !

Detailed Description

Audio / Sound stuff.

Author:
Stephane Dallongeville
Date:
08/2011

This unit provides advanced sound playback methods through differents Z80 drivers.

Z80_DRIVER_PCM
Single channel 8 bits signed sample driver.
It can play a sample (8 bit signed) from 8 Khz up to 32 Khz rate.

Z80_DRIVER_2ADPCM
2 channels 4 bits ADPCM sample driver.
It can mix up to 2 ADCPM samples at a fixed 22050 Hz Khz rate.
Address and size of samples have to be 256 bytes boundary.

Z80_DRIVER_4PCM_ENV
4 channels 8 bits signed sample driver with volume support.
It can mix up to 4 samples (8 bit signed) at a fixed 16 Khz rate.
with volume support (16 levels du to memory limitation).
Address and size of samples have to be 256 bytes boundary.
The driver does support "cutoff" when mixing so you can use true 8 bits samples :)

Z80_DRIVER_MVS
MVS music player driver.

Z80_DRIVER_TFM
TFM music player driver.

Z80_DRIVER_VGM
VGM music player driver.
It supports 1 PCM channel at a fixed 8 Khz and allows to play SFX through the named PCM channel.
Written by Sigflup and kubilus1.
Z80_DRIVER_XGM
eXtended VGM music player driver.
This driver takes VGM (or XGM) file as input to play music.
It supports 4 PCM channels at a fixed 14 Khz and allows to play SFX through PCM with 16 level of priority.
The driver is designed to avoid DMA contention when possible (depending CPU load).


Define Documentation

#define SOUND_PAN_CENTER   0xC0

Center (laft and right) speaker panning.

#define SOUND_PAN_LEFT   0x80

Left speaker panning.

#define SOUND_PAN_RIGHT   0x40

Right speaker panning.

#define SOUND_PCM_CH1   Z80_DRV_CH0_SFT

PCM channel 1.

#define SOUND_PCM_CH1_MSK   Z80_DRV_CH0

PCM channel 1 selection mask.

#define SOUND_PCM_CH2   Z80_DRV_CH1_SFT

PCM channel 2.

#define SOUND_PCM_CH2_MSK   Z80_DRV_CH1

PCM channel 2 selection mask.

#define SOUND_PCM_CH3   Z80_DRV_CH2_SFT

PCM channel 3.

#define SOUND_PCM_CH3_MSK   Z80_DRV_CH2

PCM channel 3 selection mask.

#define SOUND_PCM_CH4   Z80_DRV_CH3_SFT

PCM channel 4.

#define SOUND_PCM_CH4_MSK   Z80_DRV_CH3

PCM channel 4 selection mask.

#define SOUND_PCM_CH_AUTO   0x00

Auto select PCM channel to use.

#define SOUND_RATE_11025   4

PCM sample rate set to 11025 Hz.

#define SOUND_RATE_13400   3

PCM sample rate set to 13400 Hz.
Good compromise for rom space and quality.

#define SOUND_RATE_16000   2

PCM sample rate set to 16 Khz.

#define SOUND_RATE_22050   1

PCM sample rate set to 22050 Hz.
Best quality but take lot of rom space.

#define SOUND_RATE_32000   0

PCM sample rate set to 32 Khz.
Best quality but take lot of rom space.

#define SOUND_RATE_8000   5

PCM sample rate set to 8 Khz.
Worst quality but take less rom place.


Function Documentation

void SND_disablePSG_MVS ( u8  chan)

Disable the specified PSG channel.

Parameters:
chanPSG channel to disable.
void SND_enablePSG_MVS ( u8  chan)

Enable the specified PSG channel.

Parameters:
chanPSG channel to enable.
u8 SND_getVolume_4PCM_ENV ( const u16  channel)

Return envelop / volume level of specified channel (4 channels PCM ENV player driver).

Parameters:
channelChannel we want to retrieve envelop level.
SOUND_PCM_CH1 = channel 1
SOUND_PCM_CH2 = channel 2
SOUND_PCM_CH3 = channel 3
SOUND_PCM_CH4 = channel 4
Returns:
Envelop of specified channel.
The returned value is comprised between 0 (quiet) to 15 (loud).
u8 SND_isPlaying_2ADPCM ( const u16  channel_mask)

Return play status of specified channel (2 channels ADPCM player driver).

Parameters:
channel_maskChannel(s) we want to retrieve play state.
SOUND_PCM_CH1_MSK = channel 1
SOUND_PCM_CH2_MSK = channel 2

You can combine mask to retrieve state of severals channels at once:
isPlaying_2ADPCM(SOUND_PCM_CH1_MSK | SOUND_PCM_CH2_MSK)
will actually return play state for channel 1 and channel 2.
Returns:
Return non zero if specified channel(s) is(are) playing.
u8 SND_isPlaying_4PCM_ENV ( const u16  channel_mask)

Return play status of specified channel (4 channels PCM ENV player driver).

Parameters:
channel_maskChannel(s) we want to retrieve play state.
SOUND_PCM_CH1_MSK = channel 1
SOUND_PCM_CH2_MSK = channel 2
SOUND_PCM_CH3_MSK = channel 3
SOUND_PCM_CH4_MSK = channel 4

You can combine mask to retrieve state of severals channels at once:
isPlaying_2ADPCM(SOUND_PCM_CH1_MSK | SOUND_PCM_CH2_MSK)
will actually return play state for channel 1 and channel 2.
Returns:
Return non zero if specified channel(s) is(are) playing.
u8 SND_isPlaying_MVS ( )

Return play status for FM (MVS music player driver).

Returns:
Return non zero if FM is currently playing.
u8 SND_isPlaying_PCM ( )

Return play status (Single channel PCM player driver).

Returns:
Return non zero if PCM player is currently playing a sample
u8 SND_isPlayingPCM_XGM ( const u16  channel_mask)

Return play status of specified PCM channel (XGM music player driver).

Parameters:
channel_maskChannel(s) we want to retrieve play state.
SOUND_PCM_CH1_MSK = channel 1
SOUND_PCM_CH2_MSK = channel 2
SOUND_PCM_CH3_MSK = channel 3
SOUND_PCM_CH4_MSK = channel 4

You can combine mask to retrieve state of severals channels at once:
isPlayingPCM_XGM(SOUND_PCM_CH1_MSK | SOUND_PCM_CH2_MSK)
will actually return play state for channel 1 and channel 2.
Returns:
Return non zero if specified channel(s) is(are) playing.
u8 SND_isPlayingPSG_MVS ( )

Return play status for PSG (MVS music player driver).

Returns:
Return non zero if PSG is currently playing.
void SND_setPCM_XGM ( const u8  id,
const u8 *  sample,
const u32  len 
)

Declare a new PCM sample (maximum = 255) for the XGM music player driver.
Sample id < 64 are reserved for music while others are used for SFX so if you want to declare a new SFX PCM sample use an id >= 64.

Parameters:
idSample id:
value 0 is not allowed
values from 1 to 63 are used for music values from 64 to 255 are used for SFX
sampleSample address, should be 256 bytes boundary aligned
SGDK automatically align sample resource as needed
lenSize of sample in bytes, should be a multiple of 256
SGDK automatically adjust resource size as needed
void SND_setPCMFast_XGM ( const u8  id,
const u8 *  sample,
const u32  len 
)

Same as SND_setPCM_XGM but fast version.
This method assume that XGM driver is loaded and that 68000 has access to Z80 bus.

Parameters:
idSample id:
value 0 is not allowed
values from 1 to 63 are used for music values from 64 to 255 are used for SFX
sampleSample address, should be 256 bytes boundary aligned
SGDK automatically align sample resource as needed
lenSize of sample in bytes, should be a multiple of 256
SGDK automatically adjust resource size as needed
void SND_setVolume_4PCM_ENV ( const u16  channel,
const u8  volume 
)

Change envelop / volume of specified channel (4 channels PCM ENV player driver).

Parameters:
channelChannel we want to set envelop.
SOUND_PCM_CH1 = channel 1
SOUND_PCM_CH2 = channel 2
SOUND_PCM_CH3 = channel 3
SOUND_PCM_CH4 = channel 4
volumeVolume to set : 16 possible level from 0 (minimum) to 15 (maximum).
void SND_startDAC_MVS ( const u8 *  sample,
u16  size 
)

Start playing the specified DAC sample (MVS music player driver).

Parameters:
sampleDAC sample address.
sizeSample size.
Maximum sample size is 65536 byte.
void SND_startPlay_2ADPCM ( const u8 *  sample,
const u32  len,
const u16  channel,
const u8  loop 
)

Start playing a sample on specified channel (2 channels ADPCM player driver).
If a sample was currently playing on this channel then it's stopped and the new sample is played instead.

Parameters:
sampleSample address, should be 128 bytes boundary aligned
SGDK automatically align resource as needed
lenSize of sample in bytes, should be a multiple of 128
SGDK automatically adjust resource size as needed
channelChannel where we want to play sample.
SOUND_PCM_CH1 = channel 1
SOUND_PCM_CH2 = channel 2
loopLoop flag.
If non zero then the sample will be played in loop (else sample is played only once).
void SND_startPlay_4PCM_ENV ( const u8 *  sample,
const u32  len,
const u16  channel,
const u8  loop 
)

Start playing a sample on specified channel (4 channels PCM ENV player driver).
If a sample was currently playing on this channel then it's stopped and the new sample is played instead.

Parameters:
sampleSample address, should be 256 bytes boundary aligned
SGDK automatically align resource as needed
lenSize of sample in bytes, should be a multiple of 256
SGDK automatically adjust resource size as needed
channelChannel where we want to play sample.
SOUND_PCM_CH1 = channel 1
SOUND_PCM_CH2 = channel 2
SOUND_PCM_CH3 = channel 3
SOUND_PCM_CH4 = channel 4
loopLoop flag.
If non zero then the sample will be played in loop (else sample is played only once).
void SND_startPlay_MVS ( const u8 *  music,
const u8  loop 
)

Start playing the specified FM track (MVS music player driver).

Parameters:
musicFM track address.
loopLoop flag.
If non zero then the sample will be played in loop (else sample is played only once).
void SND_startPlay_PCM ( const u8 *  sample,
const u32  len,
const u8  rate,
const u8  pan,
const u8  loop 
)

Start playing a sample (Single channel PCM player driver).
If a sample was currently playing then it's stopped and the new sample is played instead.

Parameters:
sampleSample address, should be 256 bytes boundary aligned
SGDK automatically align resource as needed
lenSize of sample in bytes, should be a multiple of 256
SGDK automatically adjust resource size as needed
ratePlayback rate :
SOUND_RATE_32000 = 32 Khz (best quality but take lot of rom space)
SOUND_RATE_22050 = 22 Khz
SOUND_RATE_16000 = 16 Khz
SOUND_RATE_13400 = 13.4 Khz
SOUND_RATE_11025 = 11 Khz
SOUND_RATE_8000 = 8 Khz (worst quality but take less rom place)
panPanning :
SOUND_PAN_LEFT = play on left speaker
SOUND_PAN_RIGHT = play on right speaker
SOUND_PAN_CENTER = play on both speaker
loopLoop flag.
If non zero then the sample will be played in loop (else sample is played only once).
void SND_startPlay_TFM ( const u8 *  song)

Start playing the specified TFM track (TFM music player driver).

Parameters:
songTFM track address.
void SND_startPlay_VGM ( const u8 *  song)

Start playing the specified VGM track (VGM music player driver).

Parameters:
songVGM track address.
void SND_startPlay_XGM ( const u8 *  song)

Start playing the specified XGM track (XGM music player driver).

Parameters:
songXGM track address.
void SND_startPlayPCM_XGM ( const u8  id,
const u8  priority,
const u16  channel 
)

Play a PCM sample on specified channel (XGM music player driver).
If a sample was currently playing on this channel then priority of the newer sample should be are compared tthen it's stopped and the new sample is played instead.

Parameters:
idSample id (set #SND_setSample_XGM method)
priorityValue should go from 0 to 15 where 0 is lowest priority and 15 the highest one.
If the channel was already playing the priority is used to determine if the new SFX should replace the current one (new priority >= old priority).
channelChannel where we want to play sample.
SOUND_PCM_CH1 = channel 1
SOUND_PCM_CH2 = channel 2
SOUND_PCM_CH3 = channel 3
SOUND_PCM_CH4 = channel 4
void SND_startPSG_MVS ( const u8 *  music)

Start playing the specified PSG music (MVS music player driver).

Parameters:
musicPSG music address.
void SND_stopPlay_2ADPCM ( const u16  channel)

Stop playing the specified channel (2 channels ADPCM player driver).
No effect if no sample was currently playing on this channel.

Parameters:
channelChannel we want to stop.
SOUND_PCM_CH1 = channel 1
SOUND_PCM_CH2 = channel 2
void SND_stopPlay_4PCM_ENV ( const u16  channel)

Stop playing the specified channel (4 channels PCM ENV player driver).
No effect if no sample was currently playing on this channel.

Parameters:
channelChannel we want to stop.
SOUND_PCM_CH1 = channel 1
SOUND_PCM_CH2 = channel 2
SOUND_PCM_CH3 = channel 3
SOUND_PCM_CH4 = channel 4
void SND_stopPlayPCM_XGM ( const u16  channel)

Stop play PCM on specified channel (XGM music player driver).
No effect if no sample was currently playing on this channel.

Parameters:
channelChannel we want to stop.
SOUND_PCM_CH1 = channel 1
SOUND_PCM_CH2 = channel 2
SOUND_PCM_CH3 = channel 3
SOUND_PCM_CH4 = channel 4
 All Classes Files Functions Variables Typedefs Enumerations Defines